package com.example.servlet.aop;

import lombok.Getter;
import lombok.RequiredArgsConstructor;

import java.lang.annotation.*;

/**
 * 自定义注解：用于标记需要记录操作日志的方法
 * 适用于：Controller 层、Service 层中的关键业务操作
 * 如：用户注册、订单创建、数据删除、权限变更、文件导出等
 *
 * @author yourname
 * @since 2025
 */
@Target(ElementType.METHOD)           // ✅ 只能标注在方法上
@Retention(RetentionPolicy.RUNTIME)   // ✅ 运行时保留，供 AOP 读取
@Documented                           // ✅ 生成 JavaDoc
public @interface LogOperation {

    /**
     * 操作模块（如：用户管理、订单系统、财务中心）
     * 用于日志分类与统计，建议使用中文或英文缩写
     */
    String module() default "通用";

    /**
     * 操作类型（如：新增、修改、删除、查询、导出、登录、退出）
     * 用于前端展示与报表统计
     */
    OperationType operationType() default OperationType.OTHER;

    /**
     * 操作描述（可选）
     * 支持 SpEL 表达式，动态生成描述，如："{#username} 修改了订单 {#orderId}"
     * 占位符说明：
     *   - {#paramName}：方法参数名
     *   - {#result}：方法返回值
     *   - {#userId}：当前登录用户ID（自动注入）
     *   - {#userName}：当前登录用户名（自动注入）
     */
    String description() default "";

    /**
     * 是否记录请求参数（默认开启）
     * 若参数包含敏感信息（如密码、身份证），建议关闭
     */
    boolean recordParams() default true;

    /**
     * 是否记录响应结果（默认关闭，避免泄露敏感数据）
     * 如：返回用户信息、订单详情等，需谨慎开启
     */
    boolean recordResult() default false;

    /**
     * 是否记录 IP 地址（默认开启）
     * 用于追踪操作来源
     */
    boolean recordIp() default true;

    /**
     * 是否记录用户代理（User-Agent）信息（默认关闭）
     * 用于识别设备、浏览器、移动端
     */
    boolean recordUserAgent() default false;

    /**
     * 是否异步写入日志（默认开启）
     * 避免日志记录阻塞主业务流程
     */
    boolean async() default true;

    /**
     * 操作类型枚举
     */
    @Getter
    @RequiredArgsConstructor
    enum OperationType {
        INSERT("新增"),
        UPDATE("修改"),
        DELETE("删除"),
        SELECT("查询"),
        OTHER("其他");

        private final String description;
    }
}
